ODDispatcher

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODDispatcher

Superclasses
ODObject
Subclasses
none

An object of the ODDispatcher class is responsible for distributing events to part editors.

Description
When a document is opened, the session object creates a single dispatcher object. All parts of that document share the dispatcher object; you can obtain a reference to it by calling the session object's GetDispatcher method (page 607).
The dispatcher maintains a dispatch module dictionary, indexed by event type. The dictionary contains at least one internal dispatch module to handle standard events--such as mouse clicks, keystrokes, and menu commands--of a particular platform. You can extend the OpenDoc dispatching system by installing additional dispatch modules to dispatch new types of events or messages to your part editor. For more information, see the ODDispatchModule class description (page 127).
Part editors do not receive events directly from the operating system; rather, OpenDoc notifies the appropriate part editor when an event occurs. To do so, the document shell's event loop calls the dispatcher's Dispatch method (page 115) to dispatch events to part editors. The dispatcher handles the events it recognizes by using dispatch module objects to dispatch specific events to individual parts. The dispatcher locates the dispatch module for the specified event in its dispatch module dictionary and calls the dispatch module's Dispatch method (page 129). The Dispatch method in turn calls the part editor's HandleEvent method (page 526) to give the part the opportunity to handle the specified event. If your part contains embedded frames, OpenDoc can also send your part editor special mouse events that occur within and on the borders of your part's embedded frames' facets. The dispatcher leaves all other events, as well as events dispatched to parts but not handled by them, to the document shell to handle. Events not handled by the document shell are ignored. For more information on event handling in OpenDoc, see the chapter on user events in the OpenDoc Programmer's Guide for the MacOS.

Event Monitoring
OpenDoc allows you to monitor the event stream without interfering with it. By registering a dispatch module as a monitor for a specified event type, OpenDoc notifies the dispatch module when an event of that type occurs. You might use a monitor in a debugging environment to monitor events and display a log of the events in a window. In general, you should install monitors and not patch the dispatch module. Patching occurs when the creator of the new dispatch module saves the existing dispatch module and then installs its own replacement dispatch module that calls the original.

Scheduling Idle Time
On platforms with the concept of idle time, such as the Mac OS platform, OpenDoc permits your part to receive idle-time events, also called null events. Your part must register either itself or each frame that is to receive null events by calling the dispatcher's RegisterIdle method (page 121).

Mac OS Mouse Regions
Whenever the user moves the mouse, your part editor is responsible for providing feedback to the user that corresponds to the location of the cursor on the screen. For example, most part editors set the cursor to the I-beam when the cursor is inside a text-editing part of a document and change the cursor to an arrow when the cursor is inside the scroll bar of a document. Your part editor can achieve this by setting a mouse region and handling mouse-enter, mouse-within, and mouse-leave events. Those events occur when the user moves the cursor outside the mouse region.
The mouse region defaults to a 1-by-1 pixel area at the mouse location, but can be set larger using the dispatcher's SetMouseRegion method (page 124). Your part editor should recalculate the mouse region when it receives a mouse-enter, mouse-within, or mouse-leave event, or it will continue to receive these events as long as the user moves the mouse outside the original mouse region.

Methods
This section presents summary descriptions of the ODDispatcher methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [D] are called only by the document shell or container applications. Methods marked [M] are specific to the Mac OS platform.
Dispatch Module Manipulation

AddDispatchModule
Adds the specified dispatch module for the specified event type to the dispatch module dictionary.
GetDispatchModule
Returns a reference to the dispatch module for the specified event type.
RemoveDispatchModule

Removes the dispatch module for the specified event type from the dispatch module dictionary.
Event Dispatching

Dispatch [D]
Dispatches the specified event to the appropriate part.
Redispatch
Redispatches the specified event to the appropriate part.
Event Monitoring

AddMonitor
Adds the specified dispatch module, which is a monitor for the specified event type, to the dispatch module dictionary.
RemoveMonitor
Removes the specified dispatch module, which is a monitor for the specified event type, from the dispatch module dictionary.
Cursor Manipulation

GetMouseRegion [D] [M]
Returns the current mouse region used in dispatching mouse-enter, mouse-within, and mouse-leave events.
SetMouseRegion [M]
Assigns the mouse region used in dispatching mouse-enter, mouse-within, and mouse-leave events.
InvalidateFacetUnderMouse [M]
Sets the facet pointer, corresponding to the facet under the mouse, to kODNULL.
Scheduling Idle Time

RegisterIdle [M]
Adds the specified part and frame to the list of parts interested in receiving idle time.
UnregisterIdle [M]
Removes the specified part and frame from the list of parts interested in receiving idle time.
GetSleepTime [D] [M]
Computes the amount of time the document shell can sleep before it needs to wake up to give idle time to registered frames.
SetIdleFrequency [M]
Sets the idle frequency for the specified part or frame.
Scheduling Processor Time

Yield [M]
Gives processor time to other parts.
Document Shell Termination

Exit [D]
Sets a Boolean value in the dispatcher that specifies that the document shell should terminate.
ShouldExit [D]
Returns a Boolean value that indicates whether the document shell should terminate.

Methods
AddDispatchModule
AddMonitor
Dispatch
Exit
GetDispatchModule
GetMouseRegion
GetSleepTime
InvalidateFacetUnderMouse
Redispatch
RegisterIdle
RemoveDispatchModule
RemoveMonitor
SetIdleFrequency
SetMouseRegion
ShouldExit
UnregisterIdle
Yield